home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / misc / SmartReadArgs.lha / smartreadargs / SmartReadArgs.doc < prev    next >
Encoding:
Text File  |  1998-09-07  |  9.6 KB  |  268 lines
  1. TABLE OF CONTENTS
  2. 0001 SmartReadArgs/--background--
  3. 0002 SmartReadArgs/--history--
  4. 0003 SmartReadArgs/SmartFreeArgs
  5. 0004 SmartReadArgs/SmartReadArgs
  6. SmartReadArgs/--background--
  7.  
  8. COPYRIGHT
  9.    SmartReadArgs is Copyright 1998 Thomas Aglassinger
  10.  
  11.    ExtReadArgs, its prequel, is Copyright 1994,1995 Stefan Ruppert
  12.  
  13.    Permission is granted to freely distribute the material (also only
  14.    parts of it) as long this ReadMe is included and all the copyright
  15.    notes are left unaltered except for a description of your changes.
  16.  
  17. MOTIVATION
  18.    The way of parsing ToolTypes provided by "icon.library" is rather
  19.    clumsy. This is particular annoying as many programmers and users got
  20.    used to ReadArgs(), which does the argument handling for many CLI
  21.    commands and ARexx ports.
  22.  
  23.    Unfortunately, ReadArgs lacks a interface to Workbench tooltypes, thus
  24.    its usage preventes your programs from being started from Workbench.
  25.  
  26.    SmartReadArgs() copies all Workbench arguments in a single string and
  27.    passes this string to the ReadArgs() function. If started from CLI, it
  28.    calls ReadArgs() without this step.
  29.  
  30. AUTHOR
  31.    Stefan Ruppert wrote most parts of the source code, designed the general
  32.    interface and implemented loads of nice features. Basically he did the
  33.    "hard work".
  34.  
  35.    He got the main idea for the implementation from Stefan Winterstein,
  36.    the author of ARoach.
  37.  
  38.    Thomas Aglassinger <agi@sbox.tu-graz.ac.at> did some minor changes,
  39.    established a more consistent naming schema, reworked the documentation
  40.    and also added support for gcc/libnix.
  41.  
  42.    Contact him in case of problems or if you made some enhancements.
  43.  
  44.    Updates are available from aminet:dev/misc/SmartReadArgs.lha.
  45.  
  46. DISCLAIMER
  47.    There is no warranty for this software package. Although the author
  48.    has tried to prevent errors, he can't guarantee that the software
  49.    package described in this document is 100% reliable. You are
  50.    therefore using this material at your own risk. The author cannot be
  51.    made responsible for any damage which is caused by using this
  52.    software package.
  53.  
  54. SmartReadArgs/--history--
  55.  
  56. HISTORY
  57.    Version 1.6, 7-Sep-1998
  58.  
  59.    - Changed name to SmartReadArgs to avoid confusion with other work based
  60.      on the same material
  61.    - Changed function parameters for SmartReadArgs() so that no more SAS/c
  62.      specific values of argc/argv are required (Of course it still works
  63.      with SAS/c, but you have to provide the WBStartup from "outside").
  64.    - Changed all #include <clib/...> to #include <proto/..>, except for
  65.      <clib/alib_stdio_protos.h> in "test.c". Where the hell is this one?
  66.    - Added feature to ignore tooltypes that are not in the template
  67.    - Added some missing includes in SmartReadArgs.c so the source codes
  68.      compile without warnings
  69.    - Changed #include <debug.h> to #include "debug.h" and provided a proper
  70.      debug.h
  71.    - The WINDOW tooltype is handled properly even if it is not entirely
  72.      written in upper case.
  73.    - Requires "utility.library" to be open as Stricmp() is used several
  74.      times
  75.    - Changed from Printf() to printf() using stdio of amiga.lib to make the
  76.      code compile easier on non-SAS environments
  77.    - Changed autodoc tool to Robodoc
  78.    - Fixed enforcer hit if no tooltypes were provided at all
  79.    - Remove some "char filename[34]" stuff and replaced the array dimension
  80.      by MAXIMUM_FILENAME_LENGTH for future compatibility
  81.    - Cleaned-up autodocs
  82.  
  83. ANCIENT HISTORY
  84.    ExtReadArgs() by Stefan Ruppert
  85.  
  86.    See aminet:dev/misc/extrdargs_v1.5.lha for the original version.
  87.  
  88.    $HISTORY
  89.    08.01.95 : 001.005 :  changed to ExtReadArgs()
  90.    24.09.94 : 001.004 :  now checks after ReadArgs the SIGBREAKF_CTRL_C
  91.                          flag, thus if anyone canceled during ReadArgs()
  92.                          help ExtReadArgs() fails
  93.    08.09.94 : 001.003 :  between two switches (no equal sign) there was
  94.                          no space, this is fixed
  95.    08.09.94 : 001.002 :  wb files now enclosed in quotes
  96.    04.09.94 : 001.001 :  bumped to version 1
  97.    19.05.94 : 000.001 :  initial
  98.  
  99. SmartReadArgs/SmartFreeArgs
  100.  
  101. NAME
  102.    SmartFreeArgs -- Free all resources allocated by SmartReadArgs().
  103.  
  104. SYNOPSIS
  105.    SmartFreeArgs(smart_args);
  106.  
  107.    void SmartFreeArgs(struct SmartArgs *);
  108.  
  109. FUNCTION
  110.    Free all resources allocated by a previous call to SmartReadArgs().
  111.  
  112. INPUTS
  113.    smart_args - Same pointer as passed to SmartReadArgs() before
  114.  
  115. NOTES
  116.    Always call SmartFreeArgs(), even if SmartReadArgs() failed! Take a look
  117.    at the example for SmartReadArgs().
  118.  
  119. SEE ALSO
  120.    SmartReadArgs()
  121.  
  122. SmartReadArgs/SmartReadArgs
  123.  
  124. NAME
  125.    SmartReadArgs -- Workbench/CLI transparent ReadArgs().
  126.  
  127. SYNOPSIS
  128.    error = SmartReadArgs(wb_startup, smart_args);
  129.  
  130.    LONG SmartReadArgs(struct WBStartup *, struct SmartArgs *);
  131.  
  132. FUNCTION
  133.    This function is a CLI/Workbench transparent interface to ReadArgs().
  134.  
  135.    In case of a Workbench start, it analyzes the WBStartup message and
  136.    possible tooltypes. These are converted to a text string that can be
  137.    passed to ReadArgs() like before.
  138.  
  139.    Tooltypes that are not part of the template are ignored. This includes
  140.    tooltypes being disabled with "(...)", NewIcons image data on systems
  141.    without NewIcons installed and all this «« Icon by some idiot »» crap.
  142.  
  143.    If the application was stared from CLI, it simply calls ReadArgs()
  144.    without the conversion step.
  145.  
  146.    If all went well you get a return value of zero. This means the passed
  147.    arguments fit the template and are ready to use. Otherwise you get a
  148.    IoErr()-like return code.
  149.  
  150. INPUTS
  151.     wb_startup - Workbench startup message. Refer to your compiler manual
  152.         to learn how to obtain it. If this is NULL, the program was
  153.         started from CLI.
  154.     smart_args - structure which holds all information used by
  155.         SmartReadArgs(). You have to setup the following fields before the
  156.         call:
  157.  
  158.         sa_Template - The template passed to ReadArgs()
  159.         sa_Parameter - ReadArgs() LONG WORD array to hold the arguments
  160.         sa_FileParameter - number of Argument in the template to use
  161.             for the files passed via WBStartup->sm_ArgList or -1, that
  162.             means you don't want any files
  163.         sa_Window - Window description string to open when the program
  164.             is started from the workbench. NULL means no window. If the
  165.             icon has a WINDOW tooltype, this value is ignored.
  166.         sa_RDArgs - RDArgs structure to use for ReadArgs() call. This
  167.             can be used to provide extended help.
  168.         sa_Buffer - Pointer to a buffer to use for the Workbench startup
  169.             or NULL, that means SmartReadArgs() allocates a buffer for you
  170.         sa_BufferSize - Size of the optional buffer. If it is smaller than
  171.             SA_MINIMUM_BUFFER_SIZE it will be adjusted.
  172.  
  173.         All other fields should be set to NULL.
  174.  
  175. RESULT
  176.    Zero for success. You can check the sa_Flags field for the
  177.    SAF_WORKBENCH flag to learn how the program was started.
  178.  
  179.    Otherwise an IoErr()-like error code is returned. This can be passed
  180.    directly to PrintFault() or similar.
  181.  
  182. NOTES
  183.    Always call SmartFreeArgs(), even if SmartReadArgs() failed! See example
  184.    below.
  185.  
  186.    This function requires "dos.library", "icon.library" and
  187.    "utility.library" to be opened by the application. Normally this
  188.    already has been done by the compiler startup code.
  189.  
  190.    There is a not widely known feature of ReadArgs(): with templates like
  191.    "FROM/M/A,TO/A", you can select the files from workbench performing the
  192.    following steps:
  193.  
  194.    - Select the program
  195.    - Select the FROM files
  196.    - Select and double click the TO file
  197.  
  198.    This is available because ReadArgs() grabs the last string from a
  199.    multi-argument FROM and uses it as the TO parameter, if none is passed
  200.    explicitely.
  201.  
  202. BUGS
  203.    There are some known problems when used with GCC, mostly related to the
  204.    fact that I never bothered creating a useable developer environment
  205.    around it (and I'm not sure if this is even possible >:) ...):
  206.  
  207.    - Debugging output shows up in the console instead of SER:. Does
  208.      debug.lib exist for gcc? (Wasn't there this strange hunk2gcc
  209.      converter?)
  210.    - "Read from 0" Enforcer hit in SmartReadArgs(). Couldn't figure out
  211.      the exact location yet because of the asynchronous debugging output
  212.      mentioned above.
  213.  
  214.    For someone with a reasonable experience with GCC, it should be easy to
  215.    fix this.
  216.  
  217.    The SAS/c implementation does not have these problems.
  218.  
  219. SEE ALSO
  220.    SmartFreeArgs(), dos.library/ReadArgs(), icon.library/GetDiskObjectNew()
  221.  
  222. EXAMPLE
  223.    The main archiev comes with a "test.c" and a couple of icons to start
  224.    the corresponding executable "test". Take a look at the source code and
  225.    play with it.
  226.  
  227.    See below for a smaller code segment that expects the "dos.library",
  228.    "icon.library" and "utility.library" to be open already.
  229.  
  230. SOURCE
  231.     int main(int argc, STRPTR argv[])
  232.     {
  233.        struct SmartArgs smart_args =
  234.        {NULL};
  235.        LONG argument[2];
  236.        LONG error;
  237.     
  238.        /* Obtain WBStartup; depends on your compiler environment */
  239.        struct WBStartup *wb_startup = NULL;
  240.     #ifdef __GNUC__
  241.        wb_startup = _WBenchMsg;
  242.     #else
  243.        if (argc == 0)
  244.        {
  245.           wb_startup = (struct WBStartup *) argv;
  246.        }
  247.     #endif
  248.     
  249.        smart_args.sa_Template = "FILES/M/A,VERBOSE";
  250.        smart_args.sa_Parameter = argument;
  251.        smart_args.sa_FileParameter = 0;
  252.        smart_args.sa_Window = "CON:////My WB-Window/AUTO/CLOSE/WAIT";
  253.     
  254.        error = SmartReadArgs(wb_startup, &smart_args);
  255.        if (error == 0)
  256.        {
  257.           /* do something */
  258.        }
  259.        else
  260.        {
  261.           PrintFault(error, "MyProgram");
  262.        }
  263.     
  264.        SmartFreeArgs(&smart_args);
  265.     
  266.        return ((error == 0) ? RETURN_OK : RETURN_FAIL);
  267.     }
  268.